###################################################################

 ########    ####     ####      ############################   
    ##       ####    #####    ################################ 
    ##       ## ##   ## ##   ##################################
    ##       ##  ## ##  ##   ##################################
    ##       ##   ###   ##    ################################ 
    ##       ##   ###   ##      ############################   
                                                               
                                                               
    ##############################      ########      ######## 
  ##################################    ###   ####    ##    ###
 ####################################   ###     ###   ######## 
 ####################################   ###     ###   ######## 
  ##################################    ###   ####    ##    ###
    ##############################      ########      ######## 

The Movie Database, tag source for Mp3tag using the official API

####################!!! IMPORTANT !!! #############################
Initial topic:		https://community.mp3tag.de/t/ws-themoviedb/48029/12
How to install:		https://community.mp3tag.de/t/freedb-and-web-sources/2748/4
How to get an API key:	https://developer.themoviedb.org/docs/getting-started
###################################################################

[2020-02-27] v1.00 Initial version by Sweder
	- scope of tags as comprehensive as possible for maximum compatibility
	  with players, media servers etc
	- including XML for iTunes storred in filed "iTunMOVI"

[2025-04-10] v1.01 TV Episode (Template v1.0) by RobertM
	- direct results using TMBD ID by removing IndexURL and using AlbumURL
	- get TV season/episode level information

[2025-11-08] v1.02 Multi Search by arb
	- Search for Movies and TV Shows
	- ID for direct access to Movies and TV Shows
	- process multiple episodes using TV season or list of episodes
	- .inc file for ParserScriptAlbum
	- .settings file

[2025-11-08] v1.03 by Florian/arb
	- missing escapes for { and }, a few unescaped ", and the
	  naming of Output (which is case-sensitive on macOS)
	- fixed ITUNEXTC %placeholder% when no ratings available

[2025-12-18] v1.04 by arb
	New files
	- "Get - Alternative Titles".src, returns all alternative titles
	- "Get - Content Ratings".src, returns all language/region ratings
	- "Get - Posters and Stills".src, returns for movies/TV episodes
	- "Get - Backdrops".src, returns all available artwork
	- "Get - Logos".src, returns all, use Preview to view .SVG files
	- "Search - Movie".src, can filter by premiere year
	- "Search - TV".src, supports grouping by region
	- "Check - Primary Translations".src, returns langauge-REGION
	- "Check - Languages".src, prefers user's input or default
	- "Check - Regions".src, prefers user's input or default
	- "Check - Content Ratings - Movie".src, user's input or default
	- "Check - Content Ratings - TV".src, user's input or default
	- "Sort Tags".mta, Action that creates several SORT tags

	All files
	- improved functionality with new commands
	- attempted a modular coding structure across files
	- added COUNTRYID, ISO 3166-1 countries/regions
	- origin country at start of COUNTRY (if available)
	- improved alternative titles, less similar versions
	- removed TITLESORT/TVSORT due to performance
	- episode ranges supported, use - for a range e.g. 1,5-10,12
	- changed ID .src's inputs to prefer using ID, not URL
	- Search .src's inputs can use SORT/ALBUM/GROUPING as a failsafe
	- fixed cover sizes when not set to "Original"
	- new tags for better MKV support in Windows File Explorer

	Search .src's
	- "Search" now "Search - Multi", basic preview for people
	- "Search or ID" now in Extra as "Concept - Search or ID"
	- pages now supported
	- now passes website preview to Adjust Tags
	- can prioritise results by preference
	- now shows full TMDB ID (movie/123 or tv/123)
	- now shows searched/default [language-REGION] when available
	- API key moved to IndexUrl, can use with no language-REGION

	ID .src's
	- "ID - TV Seasons/Episodes" now "Get - TV Seasons/Episodes"
	- "Get - TV Seasons" now has episode filtering

	Results.inc
	- changed Do Whiles to json_foreach for crew processing
	- empty crew jobs in INVOLVEDPEOPLE now labelled "Crew"

	Settings.settings
	- re-organised under headings
	- added "Group searches by", top results then language-REGION
	- added "Preview Overview", useful if it prompt runs slow
	- added "Default content rating when none found"
	- added "Mark explicit if no content ratings found"
	- added "Stop if any episodes missing", if exact results needed
	- added "Skip to single search result", if you're "feeling lucky"
	- expanded "Extra Tags" into "Remap Tags" to enable MKV specific tags
	- "Mark as Explicit" usable, use ^ and $ for exact matches
	- "Episode Limit" usable, use 0 to get all episodes
	- "Language" partially usable as default translation
	- "Region" partially usable as default for content ratings

[2025-12-20] v1.04.1 by arb
	Results.inc
	- figured out how to assign TVEPISODE to TRACK

[2026-01-25] v1.05 by arb
	New files
	- "Quick Search - Movie".src, quick and basic metadata
	- "Quick Search - TV".src
	- "Quick ID".src
	- "Quick Results".inc, necessary for the above files
	- "Remap Tags#MKV".mta, remaps existing tags for compatibility
	- "Remap Tags#MP4".mta, remaps and generates missing iTunes data
	- "Remap Tags#Auto".mta, remaps automatically based on file format
	- "Clean Tags.mta", standardises punctuation, validates tags and trims whitespace
	- "Fix Tags.mta", all-in-one solution to clean, remap and create tags

	Settings.inc
	- added separators and moved things for better clarity
	- added "Setup", "Metadata", "Content Ratings" and "Advisory" headings
	- moved region and language under "Setup"
	- added "TV Movie" and "Short Film" checks for media types.
	- added fallbacks to customise where a content rating can be found
	- added "Use region in LAW_RATING", choose with or without
	- Renamed "None" to "MP4" in remapping
	- clarified "Default content rating" also applies to LAW_RATING

	Search - Movie.src
	- support for RELEASETIME in Year search

	Get - Content Ratings.src
	- fixed remapping for MP4/MKV

	Results.inc
	- fixed remapping for MP4/MKV
	- made COMMENT a basic tag rather than just an MKV remap
	- COMMENT now includes tags not indexed by file explorers
	- fixed an extra tab generated in ITUNMOVI

	Add Sort Tags.mta
	- "Sort Tags" renamed to "Add Sort Tags" for clarity
	- support for multi-value tags (i.e. delimited with \\)
	- adds ALBUM and TRACK into movie TITLESORT for better sorting

[2026-04-28] v1.06 by arb
	All files
	- now have versions appended to top for easier identification
	- .ico files for every web source (suited for Default appearance)
	- updated README.txt with swanky ASCII artwork
	- added Length column in "Adjust Tags"
	- added [MinAppVersionMac]
	- RELEASETIME now a basic tag
	- removed COLLECTION, not actually an MKV tag
	- removed ACTOR->ARTIST, DIRECTOR->ALBUMARTIST and WRITER->COMPOSER remaps
	- replaced GROUPING with CONTENTGROUP
	- remap CONTENTGROUP->GROUPING in max compatibility
	- added EXPLICIT, equivalent of ITUNESADVISORY
	- added SCREENPLAY for MP4, SCREENPLAY_BY for MKV
	- SCREENPLAY values are now separate from WRITER but stay combined for ITUNMOVI
	- added EDITOR for MP4, EDITED_BY for MKV
	- added NARRATOR when found in crew
	- added ARTIST when a musician is found in crew and cast as singing voice
	- added LYRICIST when a musician found in crew
	- added CONDUCTOR when a musician found in crew
	- added COMPOSER when a musician is found in crew
	- added CHARACTER, may require manual review as it captures a LOT of entries
	- added CREATOR, for completion's sake
	- added more job roles to be assigned to PRODUCER/WRITER for better detection

	Settings.settings
	- added "Year" to set YEAR as YYYY-MM-DD or YYYY

	Results.inc
	- fixed newlines on ITUNMOVI
        - fixed ITUNEXTC/LAW_RATING when regions found but no values for ratings
	- fixed episodes not being returned when missing an air date

	(Quick) Search - Movie/TV/Multi.src / Concept - Search or ID.src
	- prioritises SORT tags over normal tags for searching

	Quick Results.inc
	- added CONTENTGROUP

	Get - Posters and Stills.inc
	- clearer error when a season/episode exists but has no posters/stills

	Get - Posters and Stills / Backdrops / Logos.inc
	- quick UI clarifiation for previewing ALL images via website

[2026-10-03] v1.07
[@arb]
	All files
	- a radical new way to install and update tag sources and toolbars with Configurators,
	  all done through Mp3tag! (currently tested only on Windows, cross-compatibility TBD)
	- API keys, language-REGION, search filter terms can be stored and used from settings
	  using Configurators
	- toolbar icons are quick and easy to assign between Default/Default (Dark)/Original
	  using Configurators
	- API key will be cleared from .src when updated if invalid/removed from settings
	  using Configurators
	- can now be made into Quick versions via setting
	- data requests lowered in Quick modes
	- reorganised folders for for easier installation/access for Configurators
	- updated !!! IMPORTANT !!! to reflect new API key updating method
	- updated .ico's to Fluent UI Icons standardisation with custom ones here and there
	- changed certain Use commands to UseFormat for reliability if no value
	- better failsafes for punctuation like quotes
	- auto-fill search by TVEPISODE when a single file selected
	- debug files automatically route to sources folder in Windows
	- changed IndexInput/AlbumInput to !IndexInput/!AlbumInput
	- changed Index/Album to !IndexDebug/!AlbumDebug
	- made indenting all tabs and stricter heirarchy
	- fixed bad folding in text editors with a missing json_unselect_object

	New Files
	- "Configurators - File 1/2".mte's, necessary for Configurators to work
	- "Configurator".mp3, simple files corresponding to an action, source or tool
	- "Update Tag Source".mta, the one you've all been waiting for...
	- "Install a Tool".mta, adds even the most complicated of tools easy-peasy
	- "Add to Toolbar".mta's, add functionality easily to your main or custom toolbar
	- "Change Toolbar Icons".mta's, alter any icons found from specific icons folders
	- "_Refresh Configurators".mta, for clearing extra TEMP_ tags or updating filenames
	- even more .ico's, icons to go with Configurators and installed functionality

	Removed Files
	- "Search - Multi".src, made redundant by "Search - Any or ID"
	- "ID".src, made redundant by "Search - Any or ID"
	- "Quick" src.'s/.inc, made redundant by setting
	- Icon.icl files, will restore if there's interest
	- Actions, will return once upgraded

	Search .src's
	- "Search - Any or ID", renamed from "Concept - Search or ID" for organisation
	- "Search - Movies", renamed from "Search - Movie" for consistency
	- "Search - TV Shows", renamed from "Search - TV" for consistency
	- improved auto-filling searches for TV content
	- $trim() in all text search entries

	External ID .src's
	- renamed to official names: IMDb, TheTVDB and Wikidata
	- upgraded to show results for movie, TV show, season and episode

	TMDB.inc
	- renamed from "TMDB#Results" for organisation
	- made CREATOR output processing ridiculously simpler
	- skips ITUNMOVI if empty due to no data available
	- added basic $dedup()'s to INVOLVEDPEOPLE
	- more failsafes for delimiters in INVOLVEDPEOPLE
	- fixed potential error with credits processing where last value could be removed
	- fixed occurence where season credits have a different JSON scheme
	- fixed loops from recent change to json_foreach commands

	Results.inc / Get - Alternative Titles.src
	- removed punctuation filtering from ORIG tags so they're truly the original

	TMDB#Settings.settings
	- "Experimental" heading removed
	- "API Key", "Language" and "Region" can now be used with Configurators
	- added "Search filter", can list comma-delimited letters like $replace()
	- added "Quick Mode", toggle between standard/quick processing

[2026-10-05] v1.07.1
[@arb]
	All .src's
	- fixed missing carriage return when inserting API key

	Configurators#Update Tag Source.mta
	- fixed missing carriage return when inserting API key
	- fixed an issue where COMMENT would show entire .src in search filter section
	- fixed TEMP_ tags not clearing

	TMDB#Settings.settings
	- added gear icons to settings that are compatible with Update Tag Source

###################################################################
References

Searching
https://developer.themoviedb.org/docs/search-and-query-for-details
https://developer.themoviedb.org/reference/search-multi
https://developer.themoviedb.org/reference/search-movie
https://developer.themoviedb.org/reference/search-tv

Results
https://developer.themoviedb.org/reference/movie-details
https://developer.themoviedb.org/reference/tv-series-details
https://developer.themoviedb.org/reference/tv-season-details

Configuration
https://developer.themoviedb.org/reference/configuration-countries
https://developer.themoviedb.org/reference/configuration-languages
https://developer.themoviedb.org/reference/configuration-primary-translations
https://developer.themoviedb.org/reference/configuration-details
https://developer.themoviedb.org/reference/configuration-jobs

Tag Mapping
https://docs.mp3tag.de/mapping/
https://id3.org/id3v2.4.0-frames
https://kodi.wiki/view/Video_file_tagging
https://kodi.wiki/view/NFO_files
https://jellyfin.org/docs/general/server/metadata/nfo
https://www.matroska.org/technical/tagging.html
https://www.reddit.com/r/PleX/comments/1i26opa/guidance_on_compatibility_with_mp4_tags/
https://www.mediamonkey.com/wiki/WebHelp:About_Track_Properties/5.0
https://wiki.hydrogenaudio.org/index.php?title=Tag_Mapping
https://community.mp3tag.de/t/mp4-felder-atom-box-in-anderer-software/48614
https://help.imdb.com/article/contribution/titles/plots/G56STCKTK7ESG7CP?ref_=helpart_nav_25#
https://github.com/SublerApp/Subler/blob/e7a4d7af09dacd5b6f29305b8283e877dfdf3275/Ratings.json#L72C1-L93C2
https://exiftool.org/TagNames/PLIST.html
https://softwarerecs.stackexchange.com/questions/46769/enhancing-windows-explorer-to-view-mkv-tags-in-details-panel
https://www.filebot.net/forums/viewtopic.php?t=4065
https://kodi.wiki/view/3D#How_Kodi_does_3D_detection
https://emby.media/support/articles/3D-Videos.html
https://forum.makemkv.com/forum/viewtopic.php?t=4781&start=75
https://www.matroska.org/technical/elements.html
https://picard-docs.musicbrainz.org/en/appendices/tag_mapping.html